%% /usr/local/src/lcc/lcc-4.1.beta.7/tst/README, Fri Mar 30 05:09:48 2001
%% Edit by Nelson H. F. Beebe <beebe@math.utah.edu>

This directory of test files for the lcc validation suite contains
preprocessed C code for standalone programs in the *.c files, from the
src/*.c files, together with corresponding input files, *.0, for their
executables.  Two directories are needed, because most C compilers
demand that source files end in .c.

Companion directories ../$ARCHITECTURE/$OS/tst contain corresponding
files named like this:

	*.1bk	output to stderr from lcc during generation of the *.sbk
		files from the *.c files.

	*.2bk	output to stderr from lcc during compilation and linking
		of the src/*.c files.

	*.3bk	output to stdout when the program is compiled and run 
		on that architecture and operating system after compilation
		and linking using lcc.

	*.4bk	output to stderr when the program is run on that 
		architecture and operating system after compilation
		and linking using lcc.

	*.sbk	assembly code produced by lcc.  

The preprocessing step is essential to ensure that lcc sees exactly
the same code on all platforms.

Originally, these test files required preprocessing on each platform,
but that led to failures of the validation suite when different code
was produced on several platforms because included data structures,
such as FILE from <stdio.h>, differed.

Thus, to augment this validation suite, place the new code in ./src,
then do something like this (assuming sh/bash/ksh syntax):

	cd src
	lcc -E foo.c >../foo.c

This was done on a Sun Solaris 2.7 system for all of the current test
files.  In principle, it could be done on any system, but it is
important that the resulting code can be compiled anywhere.  Some
systems might use C language extensions, or nonstandard data types, in
system header files (e.g., FreeBSD-4.1.1 uses "long long int" in the
FILE struct in <stdio.h>) that would cause compilation errors on other
systems.

Together, the ./*.c, ./src/*.c, and ../$ARCHITECTURE/$OS/tst/*.{1bk,2bk,sbk}
files permit verification of cross compilation (by comparing the
generated .s file from the .c file in this directory with the .sbk
file), and verification of compilation and runtime output from the
./src/*.c files on the current platform.  The ../Makefile.in file
contains check-xxx targets that do this for all supported platforms.

When a new test file is added to the suite in foo.c and src/foo.c,
corresponding output files foo.sbk, foo.1bk, and foo.2bk must be added
to each of the ../$ARCHITECTURE/$OS/tst/ directories as well.

Most test programs should be expected to run quickly, and to produce
identical output on each platform, so the results can be collected on
any one of them, then copied into all of the other required places.
Among the current test files, the paranoia floating-point test is a
notable exception: its output is expected to differ on each target
$ARCHITECTURE/$OS. The output of the cq and limits tests also differs.
All others should produce identical output.

If you do not have access to all of the supported platforms when
adding a new test file, you'll need to ask other lcc users to supply
the output .1bk, .2bk, and .sbk files for the missing platforms.
